@okta/okta-auth-js
Advanced tools
@okta/okta-auth-js is a JavaScript library that provides a set of tools for integrating Okta's authentication and authorization services into your web applications. It allows you to handle user authentication, manage tokens, and interact with Okta's APIs.
User Authentication
This feature allows you to authenticate users by their username and password. The code sample demonstrates how to sign in a user and handle the authentication transaction.
const OktaAuth = require('@okta/okta-auth-js');
const authClient = new OktaAuth({
issuer: 'https://{yourOktaDomain}/oauth2/default',
clientId: '{clientId}',
redirectUri: 'http://localhost:8080/login/callback'
});
async function signIn(username, password) {
try {
const transaction = await authClient.signIn({ username, password });
if (transaction.status === 'SUCCESS') {
authClient.token.getWithRedirect({
sessionToken: transaction.sessionToken
});
} else {
throw new Error('We cannot handle the ' + transaction.status + ' status');
}
} catch (err) {
console.error(err);
}
}Token Management
This feature allows you to manage tokens, including obtaining tokens without prompting the user. The code sample demonstrates how to get an ID token using the OktaAuth client.
const OktaAuth = require('@okta/okta-auth-js');
const authClient = new OktaAuth({
issuer: 'https://{yourOktaDomain}/oauth2/default',
clientId: '{clientId}',
redirectUri: 'http://localhost:8080/login/callback'
});
async function getToken() {
try {
const token = await authClient.token.getWithoutPrompt({
responseType: 'id_token',
scopes: ['openid', 'profile', 'email']
});
console.log(token);
} catch (err) {
console.error(err);
}
}Session Management
This feature allows you to manage user sessions. The code sample demonstrates how to check the current session using the OktaAuth client.
const OktaAuth = require('@okta/okta-auth-js');
const authClient = new OktaAuth({
issuer: 'https://{yourOktaDomain}/oauth2/default',
clientId: '{clientId}',
redirectUri: 'http://localhost:8080/login/callback'
});
async function checkSession() {
try {
const session = await authClient.session.get();
console.log(session);
} catch (err) {
console.error(err);
}
}Auth0.js is a JavaScript library for integrating Auth0's authentication and authorization services into your web applications. It provides similar functionalities to @okta/okta-auth-js, such as user authentication, token management, and session handling. However, it is designed to work with Auth0's platform instead of Okta.
Firebase Authentication is a service provided by Google Firebase that offers backend services, easy-to-use SDKs, and ready-made UI libraries to authenticate users to your app. It supports various authentication methods, including email/password, phone number, and social providers like Google, Facebook, and Twitter. While it provides similar functionalities to @okta/okta-auth-js, it is part of the larger Firebase ecosystem.
Passport is a popular authentication middleware for Node.js. It provides a comprehensive set of strategies for authenticating with different services, including local username/password, OAuth, and OpenID Connect. While it offers similar functionalities to @okta/okta-auth-js, it is more flexible and can be used with various authentication providers.
The Okta Auth SDK builds on top of our Authentication API and OAuth 2.0 API to enable you to create a fully branded sign-in experience using JavaScript.
For an overview of the client's features and authentication flows, check out our developer docs.
Read our contributing guidelines if you wish to contribute.
You can include Okta Auth JS in your project either directly from the Okta CDN, or by packaging it with your app via our npm package, @okta/okta-auth-js.
Loading our assets directly from the CDN is a good choice if you want an easy way to get started with okta-auth-js, and don't already have an existing build process that leverages npm for external dependencies.
To use the CDN, include links to the JS and CSS files in your HTML:
<!-- Latest CDN production Javascript: 1.11.0 -->
<script
src="https://ok1static.oktacdn.com/assets/js/sdk/okta-auth-js/1.11.0/okta-auth-js.min.js"
type="text/javascript"></script>
The okta-auth-js.min.js file will expose a global OktaAuth object. Use it to bootstrap the client:
var authClient = new OktaAuth({/* configOptions */});
Using our npm module is a good choice if:
You have a build system in place where you manage dependencies with npm.
You do not want to load scripts directly from third party sites.
To install @okta/okta-auth-js:
# Run this command in your project root folder.
[project-root-folder]$ npm install @okta/okta-auth-js --save
After running npm install:
The minified auth client will be installed to node_modules/@okta/okta-auth-js/dist. You can copy the dist contents to a publicly hosted directory. However, if you're using a bundler like Webpack or Browserify, you can simply import the module using CommonJS.
var OktaAuth = require('@okta/okta-auth-js');
var authClient = new OktaAuth(/* configOptions */);
Creates a new instance of the Okta Auth Client with the provided options. The client has many config options. The only required option to get started is url, the base url for your Okta domain.
config - Options that are used to configure the clientvar authClient = new OktaAuth({url: 'https://acme.okta.com'});
The goal of an authentication flow is to set an Okta session cookie on the user's browser or retrieve an id_token or access_token. The flow is started using signIn.
username - User’s non-qualified short-name (e.g. dade.murphy) or unique fully-qualified login (e.g dade.murphy@example.com)password - The password of the usersendFingerprint - Enabling this will send a X-Device-Fingerprint header. Defaults to falseauthClient.signIn({
username: 'some-username',
password: 'some-password'
})
.then(function(transaction) {
if (transaction.status === 'SUCCESS') {
authClient.session.setCookieAndRedirect(transaction.sessionToken); // Sets a cookie on redirect
} else {
throw 'We cannot handle the ' + transaction.status + ' status';
}
})
.fail(function(err) {
console.error(err);
});
Signs the user out of their current Okta session.
authClient.signOut()
.then(function() {
console.log('successfully logged out');
})
.fail(function(err) {
console.error(err);
});
Starts a new password recovery transaction for a given user and issues a recovery token that can be used to reset a user’s password.
username - User’s non-qualified short-name (e.g. dade.murphy) or unique fully-qualified login (e.g dade.murphy@example.com)factorType - Recovery factor to use for primary authentication. Supported options are SMS, EMAIL, or CALLrelayState - Optional state value that is persisted for the lifetime of the recovery transactionauthClient.forgotPassword({
username: 'dade.murphy@example.com',
factorType: 'SMS',
})
.then(function(transaction) {
return transaction.verify({
passCode: '123456' // The passCode from the SMS or CALL
});
})
.then(function(transaction) {
if (transaction.status === 'SUCCESS') {
authClient.session.setCookieAndRedirect(transaction.sessionToken);
} else {
throw 'We cannot handle the ' + transaction.status + ' status';
}
})
.fail(function(err) {
console.error(err);
});
Starts a new unlock recovery transaction for a given user and issues a recovery token that can be used to unlock a user’s account.
username - User’s non-qualified short-name (e.g. dade.murphy) or unique fully-qualified login (e.g dade.murphy@example.com)factorType - Recovery factor to use for primary authentication. Supported options are SMS, EMAIL, or CALLrelayState - Optional state value that is persisted for the lifetime of the recovery transactionauthClient.unlockAccount({
username: 'dade.murphy@example.com',
factorType: 'SMS',
})
.then(function(transaction) {
return transaction.verify({
passCode: '123456' // The passCode from the SMS
});
})
.then(function(transaction) {
if (transaction.status === 'SUCCESS') {
authClient.session.setCookieAndRedirect(transaction.sessionToken);
} else {
throw 'We cannot handle the ' + transaction.status + ' status';
}
})
.fail(function(err) {
console.error(err);
});
Validates a recovery token that was distributed to the end-user to continue the recovery transaction.
recoveryToken - Recovery token that was distributed to end-user via an out-of-band mechanism such as emailauthClient.verifyRecoveryToken({
recoveryToken: '00xdqXOE5qDZX8-PBR1bYv8AESqIFinDy3yul01tyh'
})
.then(function(transaction) {
if (transaction.status === 'SUCCESS') {
authClient.session.setCookieAndRedirect(transaction.sessionToken);
} else {
throw 'We cannot handle the ' + transaction.status + ' status';
}
})
.fail(function(err) {
console.error(err);
});
Calls the Webfinger API and gets a response.
resource - URI that identifies the entity whose information is sought, currently only acct scheme is supported (e.g acct:dade.murphy@example.com)rel - Optional parameter to request only a subset of the information that would otherwise be returned without the "rel" parameterrequestContext - Optional parameter that provides Webfinger the context of that which the user is trying to access, such as the path of an appauthClient.webfinger({
resource: 'acct:john.joe@example.com',
rel: 'okta:idp',
requestContext: '/home/dropbox/0oa16630PzpWKeWrH0g4/121'
})
.then(function(res) {
// use the webfinger response to select an idp
})
.fail(function(err) {
console.error(err);
});
Creates a browser fingerprint.
timeout - Time in ms until the operation times out. Defaults to 15000.authClient.fingerprint()
.then(function(fingerprint) {
// Do something with the fingerprint
})
.fail(function(err) {
console.log(err);
})
Resumes an in-progress transaction. This is useful if a user navigates away from the login page before authentication is complete.
var exists = authClient.tx.exists();
if (exists) {
authClient.tx.resume()
.then(function(transaction) {
console.log('current status:', transaction.status);
})
.fail(function(err) {
console.error(err);
});
}
Check for a transaction to be resumed. This is synchronous and returns true or false.
var exists = authClient.tx.exists()
if (exists) {
console.log('a session exists');
} else {
console.log('a session does not exist');
}
When Auth Client methods resolve, they return a transaction object that encapsulates the new state in the authentication flow. This transaction contains metadata about the current state, and methods that can be used to progress to the next state.
Sample transactions and their methods:
Terminates the current auth flow.
transaction.cancel()
.then(function() {
// transaction canceled. You can now start another with authClient.signIn
});
The user account is locked; self-service unlock or admin unlock is required.
{
status: 'LOCKED_OUT',
unlock: function(options) { /* returns another transaction */ },
cancel: function() { /* terminates the auth flow */ },
data: { /* the parsed json response */ }
}
username - User’s non-qualified short-name (e.g. dade.murphy) or unique fully-qualified login (e.g dade.murphy@example.com)factorType - Recovery factor to use for primary authentication. Supported options are SMS, EMAIL, or CALLrelayState - Optional state value that is persisted for the lifetime of the recovery transactiontransaction.unlock({
username: 'dade.murphy@example.com',
factorType: 'EMAIL'
});
The user’s password was successfully validated but is expired.
{
status: 'PASSWORD_EXPIRED',
expiresAt: '2014-11-02T23:39:03.319Z',
user: {
id: '00ub0oNGTSWTBKOLGLNR',
profile: {
login: 'isaac@example.org',
firstName: 'Isaac',
lastName: 'Brock',
locale: 'en_US',
timeZone: 'America/Los_Angeles'
}
},
changePassword: function(options) { /* returns another transaction */ },
cancel: function() { /* terminates the auth flow */ },
data: { /* the parsed json response */ }
}
oldPassword - User’s current password that is expirednewPassword - New password for usertransaction.changePassword({
oldPassword: '0ldP4ssw0rd',
newPassword: 'N3wP4ssw0rd'
});
The user successfully answered their recovery question and can set a new password.
{
status: 'PASSWORD_EXPIRED',
expiresAt: '2014-11-02T23:39:03.319Z',
user: {
id: '00ub0oNGTSWTBKOLGLNR',
profile: {
login: 'isaac@example.org',
firstName: 'Isaac',
lastName: 'Brock',
locale: 'en_US',
timeZone: 'America/Los_Angeles'
}
},
resetPassword: function(options) { /* returns another transaction */ },
cancel: function() { /* terminates the auth flow */ },
data: { /* the parsed json response */ }
}
newPassword - New password for usertransaction.resetPassword({
newPassword: 'N3wP4ssw0rd'
});
The user’s password was successfully validated but is about to expire and should be changed.
{
status: 'PASSWORD_WARN',
expiresAt: '2014-11-02T23:39:03.319Z',
user: {
id: '00ub0oNGTSWTBKOLGLNR',
profile: {
login: 'isaac@example.org',
firstName: 'Isaac',
lastName: 'Brock',
locale: 'en_US',
timeZone: 'America/Los_Angeles'
}
},
policy: {
expiration:{
passwordExpireDays: 0
},
complexity: {
minLength: 8,
minLowerCase: 1,
minUpperCase: 1,
minNumber: 1,
minSymbol: 0,
excludeUsername: true
},
age:{
minAgeMinutes:0,
historyCount:0
}
},
changePassword: function(options) { /* returns another transaction */ },
skip: function() { /* returns another transaction */ },
cancel: function() { /* terminates the auth flow */ },
data: { /* the parsed json response */ }
}
oldPassword - User’s current password that is about to expirenewPassword - New password for usertransaction.changePassword({
oldPassword: '0ldP4ssw0rd',
newPassword: 'N3wP4ssw0rd'
});
Ignore the warning and continue.
transaction.skip();
The user has requested a recovery token to reset their password or unlock their account.
{
status: 'RECOVERY',
expiresAt: '2014-11-02T23:39:03.319Z',
recoveryType: 'PASSWORD', // or 'UNLOCK'
user: {
id: '00ub0oNGTSWTBKOLGLNR',
profile: {
login: 'isaac@example.org',
firstName: 'Isaac',
lastName: 'Brock',
locale: 'en_US',
timeZone: 'America/Los_Angeles'
},
recovery_question: {
question: "Who's a major player in the cowboy scene?"
}
},
answer: function(options) { /* returns another transaction */ },
recovery: function(options) { /* returns another transaction */ },
cancel: function() { /* terminates the auth flow */ },
data: { /* the parsed json response */ }
}
answer - Answer to user’s recovery questiontransaction.answer({
answer: 'My favorite recovery question answer'
});
recoveryToken - Recovery token that was distributed to end-user via out-of-band mechanism such as emailtransaction.recovery({
recoveryToken: '00xdqXOE5qDZX8-PBR1bYv8AESqIFinDy3yul01tyh'
});
The user must verify the factor-specific recovery challenge.
{
status: 'RECOVERY_CHALLENGE',
expiresAt: '2014-11-02T23:39:03.319Z',
recoveryType: 'PASSWORD', // or 'UNLOCK',
factorType: 'EMAIL', // or 'SMS'
user: {
id: '00ub0oNGTSWTBKOLGLNR',
profile: {
login: 'isaac@example.org',
firstName: 'Isaac',
lastName: 'Brock',
locale: 'en_US',
timeZone: 'America/Los_Angeles'
}
},
verify: function(options) { /* returns another transaction */ },
resend: function() { /* returns another transaction */ },
cancel: function() { /* terminates the auth flow */ },
data: { /* the parsed json response */ }
}
passCode - OTP sent to devicetransaction.verify({
passCode: '615243'
});
Resend the recovery email or text.
transaction.resend();
When MFA is required, but a user isn’t enrolled in MFA, they must enroll in at least one factor.
{
status: 'MFA_ENROLL',
expiresAt: '2014-11-02T23:39:03.319Z',
user: {
id: '00ub0oNGTSWTBKOLGLNR',
profile: {
login: 'isaac@example.org',
firstName: 'Isaac',
lastName: 'Brock',
locale: 'en_US',
timeZone: 'America/Los_Angeles'
}
},
factors: [{
provider: 'OKTA',
factorType: 'question',
questions: function() { /* returns an array of possible questions */ },
enroll: function(options) { /* returns another transaction */ }
}, {
provider: 'OKTA',
factorType: 'sms',
enroll: function(options) { /* returns another transaction */ }
}, {
provider: 'OKTA',
factorType: 'call',
enroll: function(options) { /* returns another transaction */ }
}, {
provider: 'OKTA',
factorType: 'push',
enroll: function(options) { /* returns another transaction */ }
}, {
provider: 'OKTA',
factorType: 'token:software:totp',
enroll: function(options) { /* returns another transaction */ }
}, {
provider: 'GOOGLE',
factorType: 'token:software:totp',
enroll: function(options) { /* returns another transaction */ }
}, {
provider: 'YUBICO',
factorType: 'token:hardware',
enroll: function(options) { /* returns another transaction */ }
}, {
provider: 'RSA',
factorType: 'token',
enroll: function(options) { /* returns another transaction */ }
}, {
provider: 'SYMANTEC',
factorType: 'token',
enroll: function(options) { /* returns another transaction */ }
}],
cancel: function() { /* terminates the auth flow */ },
data: { /* the parsed json response */ }
}
To enroll in a factor, select one from the factors array, then use the following methods.
var factor = transaction.factors[/* index of the desired factor */];
List the available questions for the question factorType.
var questionFactor = transaction.factors.find(function(factor) {
return factor.provider === 'OKTA' && factor.factorType === 'question';
});
questionFactor.questions()
.then(function(questions) {
// Display questions for the user to select from
});
The enroll options depend on the desired factor.
var questionFactor = transaction.factors.find(function(factor) {
return factor.provider === 'OKTA' && factor.factorType === 'question';
});
questionFactor.enroll({
profile: {
question: 'disliked_food', // all questions available using questionFactor.questions()
answer: 'mayonnaise'
}
});
var factor = transaction.factors.find(function(factor) {
return factor.provider === 'OKTA' && factor.factorType === 'sms';
});
factor.enroll({
profile: {
phoneNumber: '+1-555-415-1337',
updatePhone: true
}
});
// The passCode sent to the phone is verified in MFA_ENROLL_ACTIVATE
var factor = transaction.factors.find(function(factor) {
return factor.provider === 'OKTA' && factor.factorType === 'call';
});
factor.enroll({
profile: {
phoneNumber: '+1-555-415-1337',
updatePhone: true
}
});
// The passCode from the call is verified in MFA_ENROLL_ACTIVATE
var factor = transaction.factors.find(function(factor) {
return factor.provider === 'OKTA' && factor.factorType === 'push';
});
factor.enroll();
// The phone will need to scan a QR Code in MFA_ENROLL_ACTIVATE
var factor = transaction.factors.find(function(factor) {
return factor.provider === 'OKTA' && factor.factorType === 'token:software:totp';
});
factor.enroll();
// The phone will need to scan a QR Code in MFA_ENROLL_ACTIVATE
var factor = transaction.factors.find(function(factor) {
return factor.provider === 'GOOGLE' && factor.factorType === 'token:software:totp';
});
factor.enroll();
// The phone will need to scan a QR Code in MFA_ENROLL_ACTIVATE
var factor = transaction.factors.find(function(factor) {
return factor.provider === 'YUBICO' && factor.factorType === 'token:hardware';
});
factor.enroll({
passCode: 'cccccceukngdfgkukfctkcvfidnetljjiknckkcjulji'
});
var factor = transaction.factors.find(function(factor) {
return factor.provider === 'RSA' && factor.factorType === 'token';
});
factor.enroll({
passCode: '5275875498',
profile: {
credentialId: 'dade.murphy@example.com'
}
});
var factor = transaction.factors.find(function(factor) {
return factor.provider === 'SYMANTEC' && factor.factorType === 'token';
});
factor.enroll({
passCode: '875498',
nextPassCode: '678195',
profile: {
credentialId: 'VSMT14393584'
}
});
The user must activate the factor to complete enrollment.
{
status: 'MFA_ENROLL_ACTIVATE',
expiresAt: '2014-11-02T23:39:03.319Z',
factorResult: 'WAITING', // or 'TIMEOUT',
user: {
id: '00ugti3kwafWJBRIY0g3',
profile: {
login: 'isaac@example.org',
firstName: 'Isaac',
lastName: 'Brock',
locale: 'en_US',
timeZone: 'America/Los_Angeles'
},
},
factor: {
id: 'opfh52xcuft3J4uZc0g3',
provider: 'OKTA',
factorType: 'push',
profile: {},
activation: {
expiresAt: '2015-04-01T15:57:32.000Z',
qrcode: {
href: 'https://acme.okta.com/api/v1/users/00ugti3kwafWJBRIY0g3/factors/opfh52xcuft3J4uZc0g3/qr/00fukNElRS_Tz6k-CFhg3pH4KO2dj2guhmaapXWbc4',
type: 'image/png'
}
}
},
resend: function() { /* returns another transaction */ },
activate: function(options) { /* returns another transaction */ },
poll: function() { /* returns another transaction */ },
prev: function() { /* returns another transaction */ },
cancel: function() { /* terminates the auth flow */ },
data: { /* the parsed json response */ }
}
Send another OTP if user doesn’t receive the original activation SMS OTP.
transaction.resend();
passCode - OTP sent to devicetransaction.activate({
passCode: '615243'
});
Poll until factorResult is not WAITING. Throws AuthPollStopError if prev, resend, or cancel is called.
transaction.poll();
End current factor enrollment and return to MFA_ENROLL.
transaction.prev();
The user must provide additional verification with a previously enrolled factor.
{
status: 'MFA_REQUIRED',
expiresAt: '2014-11-02T23:39:03.319Z',
user: {
id: '00ugti3kwafWJBRIY0g3',
profile: {
login: 'isaac@example.org',
firstName: 'Isaac',
lastName: 'Brock',
locale: 'en_US',
timeZone: 'America/Los_Angeles'
},
},
factors: [{
id: 'ufsigasO4dVUPM5O40g3',
provider: 'OKTA',
factorType: 'question',
profile: {
question: 'disliked_food',
questionText: 'What is the food you least liked as a child?'
},
verify: function(options) { /* returns another transaction */ }
}, {
id: 'opfhw7v2OnxKpftO40g3',
provider: 'OKTA',
factorType: 'push',
profile: {
credentialId: 'isaac@example.org',
deviceType: 'SmartPhone_IPhone',
keys: [
{
kty: 'PKIX',
use: 'sig',
kid: 'default',
x5c: [
'MIIBIjANBgkqhkiG9w0BAQEFBAOCAQ8AMIIBCgKCAQEAs4LfXaaQW6uIpkjoiKn2g9B6nNQDraLyC3XgHP5cvX/qaqry43SwyqjbQtwRkScosDHl59r0DX1V/3xBtBYwdo8rAdX3I5h6z8lW12xGjOkmb20TuAiy8wSmzchdm52kWodUb7OkMk6CgRJRSDVbC97eNcfKk0wmpxnCJWhC+AiSzRVmgkpgp8NanuMcpI/X+W5qeqWO0w3DGzv43FkrYtfSkvpDdO4EvDL8bWX1Ad7mBoNVLWErcNf/uI+r/jFpKHgjvx3iqs2Q7vcfY706Py1m91vT0vs4SWXwzVV6pAVjD/kumL+nXfzfzAHw+A2vb6J2w06Rj71bqUkC2b8TpQIDAQAB'
]
}
],
name: 'Isaac\'s iPhone',
platform: 'IOS',
version: '8.1.3'
},
verify: function() { /* returns another transaction */ }
}, {
id: 'smsigwDlH85L9FyQK0g3',
provider: 'OKTA',
factorType: 'sms',
profile: {
phoneNumber: '+1 XXX-XXX-3355'
},
verify: function() { /* returns another transaction */ }
}, {
id: 'ostigevBq2NObXmTh0g3',
provider: 'OKTA',
factorType: 'token:software:totp',
profile: {
credentialId: 'isaac@example.org'
},
verify: function() { /* returns another transaction */ }
}, {
id: 'uftigiEmYTPOmvqTS0g3',
provider: 'GOOGLE',
factorType: 'token:software:totp',
profile: {
credentialId: 'isaac@example.org'
},
verify: function() { /* returns another transaction */ }
}],
cancel: function() { /* terminates the auth flow */ },
data: { /* the parsed json response */ }
}
To verify a factor, select one from the factors array, then use the following methods.
var factor = transaction.factors[/* index of the desired factor */];
var questionFactor = transaction.factors.find(function(factor) {
return factor.provider === 'OKTA' && factor.factorType === 'question';
});
questionFactor.verify({
answer: 'mayonnaise'
});
autoPush - Optional parameter to send a push notification immediately the next time verify is called on a push factorvar pushFactor = transaction.factors.find(function(factor) {
return factor.provider === 'OKTA' && factor.factorType === 'push';
});
pushFactor.verify({
autoPush: true
});
var factor = transaction.factors.find(function(factor) {
return factor.provider === 'YOUR_PROVIDER' && factor.factorType === 'yourFactorType';
});
factor.verify();
The user must verify the factor-specific challenge.
{
status: 'MFA_CHALLENGE',
expiresAt: '2014-11-02T23:39:03.319Z',
factorResult: 'WAITING', // or CANCELLED, TIMEOUT, or ERROR
user: {
id: '00ugti3kwafWJBRIY0g3',
profile: {
login: 'isaac@example.org',
firstName: 'Isaac',
lastName: 'Brock',
locale: 'en_US',
timeZone: 'America/Los_Angeles'
},
},
factor: {
id: 'smsigwDlH85L9FyQK0g3',
factorType: 'sms',
provider: 'OKTA',
profile: {
phoneNumber: '+1 XXX-XXX-6688'
}
},
verify: function(options) { /* returns another transaction */ },
poll: function() { /* returns another transaction */ },
prev: function() { /* returns another transaction */ },
cancel: function() { /* terminates the auth flow */ },
data: { /* the parsed json response */ }
}
passCode - OTP sent to deviceautoPush - Optional parameter to send a push notification immediately the next time verify is called on a push factortransaction.verify({
passCode: '615243',
autoPush: true
});
autoPush - Optional parameter to send a push notification immediately the next time verify is called on a push factorPoll until factorResult is not WAITING. Throws AuthPollStopError if prev, resend, or cancel is called.
transaction.poll({
autoPush: true
});
End current factor verification and return to MFA_REQUIRED.
transaction.prev();
The end of the authentication flow! This transaction contains a sessionToken you can exchange for an Okta cookie, an id_token, or access_token.
{
expiresAt: '2015-06-08T23:34:34.000Z',
status: 'SUCCESS',
sessionToken: '00p8RhRDCh_8NxIin-wtF5M6ofFtRhfKWGBAbd2WmE',
user: {
id: '00uhm5QzwyZZxjrfp0g3',
profile: {
login: 'exampleUser@example.com',
firstName: 'Test',
lastName: 'User',
locale: 'en_US',
timeZone: 'America/Los_Angeles'
}
}
}
This allows you to create a session using a sessionToken.
sessionToken - Ephemeral one-time token used to bootstrap an Okta session.redirectUri - After setting a cookie, Okta redirects to the specified URI. The default is the current URI.authClient.session.setCookieAndRedirect(transaction.sessionToken);
Returns a promise that resolves with true if there is an existing Okta session, or false if not.
authClient.session.exists()
.then(function(exists) {
if (exists) {
// logged in
} else {
// not logged in
}
});
Gets the active session.
authClient.session.get()
.then(function(session) {
// logged in
})
.catch(function(err) {
// not logged in
});
Refresh the current session by extending its lifetime. This can be used as a keep-alive operation.
authClient.session.refresh()
.then(function(session) {
// existing session is now refreshed
})
.catch(function(err) {
// there was a problem refreshing (the user may not have an existing session)
});
When you've obtained a sessionToken from the authorization flows, or a session already exists, you can obtain a token or tokens without prompting the user to log in.
oauthOptions - See OIDC ConfigurationauthClient.token.getWithoutPrompt({
responseType: 'id_token', // or array of types
sessionToken: 'testSessionToken' // optional if the user has an existing Okta session
})
.then(function(tokenOrTokens) {
// manage token or tokens
})
.catch(function(err) {
// handle OAuthError
});
Create token with a popup.
oauthOptions - See OIDC ConfigurationauthClient.token.getWithPopup(oauthOptions)
.then(function(tokenOrTokens) {
// manage token or tokens
})
.catch(function(err) {
// handle OAuthError
});
Create token using a redirect.
oauthOptions - See OIDC ConfigurationauthClient.token.getWithRedirect(oauthOptions);
Parses the access or ID Tokens from the url after a successful authentication redirect.
authClient.token.parseFromUrl()
.then(function(tokenOrTokens) {
// manage token or tokens
})
.catch(function(err) {
// handle OAuthError
});
Decode a raw ID Token
idTokenString - an id_token JWTauthClient.token.decode('YOUR_ID_TOKEN_JWT');
Returns a new token if the Okta session is still valid.
tokenToRefresh - an access token or ID token previously provided by Okta. note: this is not the raw JWT// this token is provided by Okta via getWithoutPrompt, getWithPopup, and parseFromUrl
var tokenToRefresh = {
idToken: 'YOUR_ID_TOKEN_JWT',
claims: { /* token claims */ },
expiresAt: 1449699930,
scopes: ['openid', 'email'],
authorizeUrl: 'https://example.okta.com/oauth2/v1/authorize',
issuer: 'https://example.okta.com',
clientId: 'NPSfOkH5eZrTy8PMDlvx'
};
authClient.token.refresh(tokenToRefresh)
.then(function(freshToken) {
// manage freshToken
})
.catch(function(err) {
// handle OAuthError
});
Retrieve the details about a user.
accessTokenObject - an access token returned by this library. note: this is not the raw access tokenauthClient.token.getUserInfo(accessTokenObject)
.then(function(user) {
// user has details about the user
});
Verify the validity of an ID token's claims and check the signature on browsers that support web cryptography.
idTokenObject - an ID token returned by this library. note: this is not the raw ID token JWTauthClient.token.verify(idTokenObject)
.then(function() {
// the idToken is valid
})
.catch(function(err) {
// handle AuthSdkError
});
After receiving an access_token or id_token, add it to the tokenManager to manage token expiration and refresh operations. When a token is added to the tokenManager, it is automatically refreshed when it expires.
key - Unique key to store the token in the tokenManager. This is used later when you want to get, delete, or refresh the token.token - Token object that will be addedauthClient.token.getWithPopup()
.then(function(idToken) {
authClient.tokenManager.add('my_id_token', idToken);
});
Get a token that you have previously added to the tokenManager with the given key.
key - Key for the token you want to getvar token = authClient.tokenManager.get('my_id_token');
Remove a token from the tokenManager with the given key.
key - Key for the token you want to removeauthClient.tokenManager.remove('my_id_token');
Remove all tokens from the tokenManager.
authClient.tokenManager.clear();
Manually refresh a token before it expires.
key - Key for the token you want to refresh// Because the refresh() method is async, you can wait for it to complete
// by using the returned Promise:
authClient.tokenManager.refresh('my_id_token')
.then(function (newToken) {
// doSomethingWith(newToken);
});
// Alternatively, you can subscribe to the 'refreshed' event:
authClient.tokenManager.on('refreshed', function (key, newToken, oldToken) {
// doSomethingWith(newToken);
});
authClient.tokenManager.refresh('my_id_token');
Subscribe to an event published by the tokenManager.
event - Event to subscribe to. Possible events are expired, error, and refreshed.callback - Function to call when the event is triggeredcontext - Optional context to bind the callback toauthClient.tokenManager.on('expired', function (key, expiredToken) {
console.log('Token with key', key, ' has expired:');
console.log(expiredToken);
});
authClient.tokenManager.on('error', function (err) {
console.log('TokenManager error:', err);
});
authClient.tokenManager.on('refreshed', function (key, newToken, oldToken) {
console.log('Token with key', key, 'has been refreshed');
console.log('Old token:', oldToken);
console.log('New token:', newToken);
});
Unsubscribe from tokenManager events. If no callback is provided, unsubscribes all listeners from the event.
event - Event to unsubscribe fromcallback - Optional callback that was used to subscribe to the eventauthClient.tokenManager.off('refreshed');
authClient.tokenManager.off('refreshed', myRefreshedCallback);
The only required configuration option is url. All others are optional.
var config = {
url: 'https://your-org.okta.com',
clientId: 'your-client-id',
redirectUri: 'https://your.redirect.uri/redirect'
};
var authClient = new OktaAuth(config);
url: The URL for your Okta organization
// Production org with subdomain "acme"
url: 'https://acme.okta.com'
// Can also target oktapreview and okta-emea, i.e.
url: 'https://acme.oktapreview.com'
ajaxRequest The ajax request implementation. By default, this is implemented using reqwest. To provide your own request library, implement the following interface:
method (http method)
url (target url)
args (object containing headers and data)
ajaxRequest: function(method, url, args) {
/*
args is in the form:
{
headers: {
headerName: headerValue
},
data: postBodyData
}
*/
return Promise.resolve(/* a raw XMLHttpRequest response */);
}
If you're using a bundler like webpack or browserify, we have implementations for jquery and reqwest included. To use them, import the SDK like this:
// reqwest
var OktaAuth = require('@okta/okta-auth-js/reqwest');
// jquery
var OktaAuth = require('@okta/okta-auth-js/jquery');
Options for the OpenId Connect authentication flow. This flow is required for social authentication, and requires OAuth client registration with Okta. For instructions, see Social Authentication.
These configuration options can be included when instantiating Okta Auth JS (new OktaAuth(config)) or in token.getWithoutPrompt, token.getWithPopup, or token.getWithRedirect. If included in both, the value passed in the method takes priority.
clientId: Client Id pre-registered with Okta for the OIDC authentication flow.
clientId: 'GHtf9iJdr60A9IYrR0jw'
redirectUri: The url that is redirected to when using token.getWithRedirect. This must be pre-registered as part of client registration. If no redirectUri is provided, defaults to the current origin.
redirectUri: 'https://acme.com/oauth2/callback/home'
issuer: Specify a custom issuer to perform the OIDC flow. Defaults to the baseUrl.
issuer: 'https://your-org.okta.com/oauth2/aus8aus76q8iphupD0h7'
authorizeUrl: Specify a custom authorizeUrl to perform the OIDC flow. Defaults to the issuer plus "/v1/authorize".
issuer: 'https://your-org.okta.com/oauth2/aus8aus76q8iphupD0h7',
authorizeUrl: 'https://your-org.okta.com/oauth2/aus8aus76q8iphupD0h7/v1/authorize'
userinfoUrl: Specify a custom userinfoUrl. Defaults to the issuer plus "/v1/userinfo".
issuer: 'https://your-org.okta.com/oauth2/aus8aus76q8iphupD0h7',
userinfoUrl: 'https://your-org.okta.com/oauth2/aus8aus76q8iphupD0h7/v1/userinfo'
sessionToken Specify an Okta sessionToken to skip reauthentication when the user already authenticated using the Authentication Flow.
sessionToken: '00p8RhRDCh_8NxIin-wtF5M6ofFtRhfKWGBAbd2WmE'
responseMode: Specify how the authorization response should be returned. You will generally not need to set this unless you want to override the default values for token.getWithRedirect.
okta_post_message - Used with token.getWithPopup and token.getWithoutPrompt. Uses postMessage to send the response from the popup or iframe to the origin window.
fragment - Default value when using token.getWithRedirect and responseType != 'code'. Returns the authorization response in the hash fragment of the URL after the authorization redirect.
query - Default value when using token.getWithRedirect and responseType = 'code'. Returns the authorization response in the query string of the URL after the authorization redirect.
form_post - Returns the authorization response as a form POST after the authorization redirect. Use this when using token.getWithRedirect and you do not want the response returned in the URL.
// Use form_post instead of query in the Authorization Code flow
responseType: 'code',
responseMode: 'form_post'
responseType: Specify the response type for OIDC authentication. Defaults to id_token.
Valid response types are id_token, access_token, and code. Note that code goes through the Authorization Code flow, which requires the server to exchange the Authorization Code for tokens.
// Specifying a single responseType
responseType: 'token'
// Use an array if specifying multiple response types - in this case,
// the response will contain both an ID Token and an Access Token.
responseType: ['id_token', 'token']
scopes: Specify what information to make available in the returned id_token or access_token. For OIDC, you must include openid as one of the scopes. Defaults to ['openid', 'email'].
Valid OIDC scopes: openid, email, profile, address, phone, groups, offline_access
scopes: ['openid', 'email', 'profile', 'address', 'phone', 'groups', 'offline_access']
state: Specify a state that will be validated in an OAuth response. This is usually only provided during redirect flows to obtain an authorization code. Defaults to a random string.
state: '8rFzn3MH5q'
nonce: Specify a nonce that will be validated in an id_token. This is usually only provided during redirect flows to obtain an authorization code that will be exchanged for an id_token. Defaults to a random string.
nonce: '51GePTswrm'
Clone the repo.
[path]$ git clone git@github.com:okta/okta-auth-js.git
Navigate to the new okta-auth-js folder, and install the Okta node dependencies.
[path/okta-auth-js]$ npm install
Build the SDK. The output will be under dist/browser/. The standalone version is okta-auth-js.min.js.
[path/okta-auth-js]$ npm run build
| Command | Description |
|---|---|
npm run build | Build the SDK with a sourcemap |
npm test | Run unit tests using PhantomJS |
npm run lint:report | Run eslint linting tests |
FAQs
The Okta Auth SDK
The npm package @okta/okta-auth-js receives a total of 384,050 weekly downloads. As such, @okta/okta-auth-js popularity was classified as popular.
We found that @okta/okta-auth-js demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.